/*
 *  Librarie de tipuri de date abstracte (TDA)
 
    Copyright (C) 2007  Catedra de Structuri de Date

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

/**
@file arrayqueue.h
@author Mihai Balan
@brief This header file contains the structures and functions needed to work
with queues (implemented using array lists)

It contains functions for creating a queue, destroying it and all the typical
operations on a queue (enqueue, dequeue, front).
*/

#ifndef ARRAYQUEUE_H_
#define ARRAYQUEUE_H_

struct arrayqueue_adt;

/**
@brief Pointer to structure representing a queue.

The \c ArrayQueue is implemented using a \c ArrayList . However, the 
underlying \c ArrayList should not be modified directly but only through the
appropriate functions.

As is the case with the \c ArrayList , element data is stored using a \c void*
pointer. Thus, one should note that there is no way to tell what kind of data is
stored inthe list or in a particular element.

@see AQ_New(), AQ_Free(), AQ_Enqueue(), AQ_Dequeue(), AQ_Front().
*/
typedef struct arrayqueue_adt *ArrayQueue;

/**
@brief Creates a new queue.

The function creates a new array queue (queue implemented using an
\c ArayList ).

@return pointer to the newly created stack.
*/
ArrayQueue AQ_New();

/**
@brief Destroys the specified queue.

The function frees the memory used by the structure itself as well as the memory
used by the data in the queue, so trying to access the data after the 
destruction of the queue (e.g. through a pointer) will most likely resutl in a
Access Violation / segfault.

@param queue \c ArrayQueue representing the queue to be destroyed.
*/
void AQ_Free(ArrayQueue queue);

/**
@brief Returns the size of the queue.

The function returns the number of elements in the queue.

@param queue queue to be tested.
@return number of elements in the queue. \c -1 is returned if \a queue is
\c NULL .
*/
int AQ_Size(ArrayQueue queue);

/**
@brief Determines if the queue is empty or not.

The function actually returns the value of the expression <tt>Size==0</tt>/

@param queue queue to be tested
@return \c -1 if \a queue is \c NULL, \c 1 if the queue is empty, \c 0
otherwise.
*/
int AQ_Empty(ArrayQueue queue);

/**
@brief Adds an element at the back of the queue.

The function adds the data specified by \a el at the end of the queue.

@param queue the queue to add data to.
@param *el pointer to an initialied memory location containing the data to be
added to the back of the queue.
*/
void AQ_Enqueue(ArrayQueue queue, void *el);

/**
@brief Removes an element from the front of the queue.

The function removes the element at the front of the queue. Note that the data
in that element is not freed so that it can be further referenced.

@param queue the queue on which to perform the operation.
@see AQ_Front()
*/
void AQ_Dequeue(ArrayQueue queue);

/**
@brief Retrieves the data in the element at the front of the queue.

The function returns the data in the element at the front of the queue but does
not alter in any way the \b structure of the queue. However the actual data can
be changed through the use of the \c void* pointer returned, which points to the
memory location containing the data.

@param queue the queue on which to perform the action.
@return if \a queue is \c NULL or empty, it returns \c NULL . Otherwise, it
returns a pointer to the memory location where the data in the element at the
front of the queue is stored.
*/
void *AQ_Front(ArrayQueue queue);

#endif /* ARRAYQUEUE_H_ */
